"""
Python注释的使用
学习目标：
1. 掌握单行注释的写法
2. 掌握多行注释的写法
3. 理解注释的作用和最佳实践
4. 学会文档字符串的使用
"""

# ==================== 1. 单行注释 ====================
# 这是一个单行注释
# 单行注释以 # 开头，# 后面的内容不会被执行

print("Hello, Python!")  # 这是行尾注释

# 注释可以用来解释代码
age = 18  # 定义年龄变量

# 注释也可以用来临时禁用代码
# print("这行代码被注释了，不会执行")

print()

# ==================== 2. 多行注释 ====================
"""
这是多行注释的第一种方式
使用三个双引号包裹
可以写很多行
通常用于函数、类、模块的文档说明
"""

'''
这是多行注释的第二种方式
使用三个单引号包裹
效果和三个双引号一样
'''

print("多行注释演示完成")

print()

# ==================== 3. 文档字符串 (Docstring) ====================
def greet(name):
    """
    这是一个问候函数
    
    参数:
        name (str): 要问候的人的名字
    
    返回:
        None
    
    示例:
        >>> greet("张三")
        你好，张三！
    """
    print(f"你好，{name}！")

# 调用函数
greet("李四")

# 可以通过 __doc__ 属性访问文档字符串
print("\n函数的文档字符串:")
print(greet.__doc__)

print()

# ==================== 4. 注释的最佳实践 ====================

# ✅ 好的注释：解释"为什么"
# 计算圆的面积，使用更精确的π值以提高精度
pi = 3.14159265359
radius = 5
area = pi * radius ** 2
print(f"圆的面积: {area:.2f}")

# ❌ 不好的注释：只说明"是什么"（显而易见）
# x = 10  # 给x赋值10

# ✅ 好的注释：解释复杂的逻辑
# 使用公式：华氏度 = 摄氏度 × 9/5 + 32
celsius = 25
fahrenheit = celsius * 9/5 + 32
print(f"{celsius}°C = {fahrenheit}°F")

print()

# ==================== 5. 注释的实际应用 ====================

# TODO: 待办事项标记
# TODO: 添加错误处理

# FIXME: 需要修复的问题标记
# FIXME: 这里的计算可能不准确

# NOTE: 重要提示标记
# NOTE: 这个函数在Python 3.9+才可用

# HACK: 临时解决方案标记
# HACK: 这是一个临时的解决办法，需要后续优化

print("注释标记示例")

print()

# ==================== 6. 代码块注释 ====================
# 下面是一个完整的学生信息管理示例
# ------------------------------------------------
# 功能：定义学生信息并显示
# 作者：Python初学者
# 日期：2025-10-13
# ------------------------------------------------

# 学生基本信息
student_id = "20250001"        # 学号
student_name = "王小明"         # 姓名
student_age = 20               # 年龄
student_major = "计算机科学"    # 专业

# 显示学生信息
print("=" * 50)
print("学生信息卡")
print("=" * 50)
print(f"学号：{student_id}")
print(f"姓名：{student_name}")
print(f"年龄：{student_age}")
print(f"专业：{student_major}")
print("=" * 50)

print()

# ==================== 7. 调试时的注释技巧 ====================
x = 10
y = 20

# 调试时，可以注释掉部分代码来定位问题
# result = x / 0  # 这行会报错，先注释掉
result = x + y
print(f"结果: {result}")

# 也可以添加调试输出
print(f"[DEBUG] x的值: {x}")
print(f"[DEBUG] y的值: {y}")

print()

# ==================== 8. 中英文注释 ====================
# English comments are also common in Python code
# 中文注释在中文项目中很常见
# Both are acceptable, choose based on your team's preference

name = "Python"  # 编程语言名称 | Programming language name
print(f"我正在学习 {name}")

print()

# ==================== 总结 ====================
"""
注释的作用：
1. 提高代码可读性
2. 帮助他人理解代码
3. 帮助自己记忆代码逻辑
4. 便于调试和维护
5. 作为临时禁用代码的方式

注释的原则：
1. 解释"为什么"而不是"是什么"
2. 保持注释与代码同步
3. 避免过度注释
4. 使用清晰简洁的语言
5. 对复杂逻辑必须注释
"""

print("✨ 良好的注释习惯让代码更易维护！")

